CListBox Class

Wrapper static class on top of all the Windows ListBox messages

A list box control contains a simple list from which the user can generally select one or more items. List boxes provide limited flexibility compared with List View controls.

List box items can be represented by text strings, bitmaps, or both. If the list box is not large enough to display all the list box items at once, the list box provides a scroll bar. The user scrolls through the list box items and applies or removes selection status as necessary. Selecting a list box item changes its visual appearance, usually by changing the text and background colors to those specified by the relevant operating system metrics. When the user selects or deselects an item, the system sends a notification message to the parent window of the list box.

There are two types of list boxes: single-selection (the default) and multiple-selection. In a single-selection list box, the user can select only one item at a time. In a multiple-selection list box, the user can select more than one item at a time. To create a multiple-selection list box, specify the LBS_MULTIPLESEL or the LBS_EXTENDEDSEL style.

The appearance and operation of a list box is controlled by list box styles and window styles. These styles indicate whether the list is sorted, arranged in multiple columns, drawn by the application, and so on.

Drag list boxes

A drag list box is a special type of list box that enables the user to drag items from one position to another. An application can use a drag list box to display strings in a particular sequence and enable the user to change the sequence by dragging the items into position.

Drag list boxes have the same window styles and process the same messages as standard list boxes. To create a drag list box, first create a standard list box and then call the MakeDragList function.

See: About List Boxes

Include file: CListBox.inc.

AddFile

Adds the specified filename to a list box that contains a directory listing.

FUNCTION CListBox.AddFile (BYVAL hListBox AS HWND, BYVAL pwszFileName AS WSTRING PTR) AS LONG

Return value

The return value is the zero-based index of the file that was added, or LB_ERR if an error occurs.

Remarks

The list box to which pwszFileName is added must have been filled by the DlgDirList function.

The LB_INITSTORAGE message helps speed up the initialization of list boxes that have a large number of items (more than 100). It reserves the specified amount of memory so that subsequent LB_ADDFILE messages take the shortest possible time. You can use estimates for the wParam and lParam parameters. If you overestimate, the extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the requested amount.

Usage example

CListBox.AddFile(hListBox, filename)

AddItemData

Adds item data to the list box.

FUNCTION CListBox.AddItemData (BYVAL hListBox AS HWND, BYVAL pData AS ANY PTR) AS LONG

Return value

The return value is the zero-based index of the string in the list box. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE.

AddString

Adds a string to a list box. If the list box does not have the LBS_SORT style, the string is added to the end of the list. Otherwise, the string is inserted into the list and the list is sorted.

FUNCTION CListBox.AssString(BYVAL hListBox AS HWND, BYVAL pwszText AS WSTRING PTR) AS LONG

Return value

The return value is the zero-based index of the string in the list box. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE.

Remarks

If the list box has an owner-drawn style and the LBS_SORT style, but not the LBS_HASSTRINGS style, the system sends the WM_COMPAREITEM message one or more times to the owner of the list box to place the new item properly in the list box.

The LB_INITSTORAGE message helps speed up the initialization of list boxes that have a large number of items (more than 100). It reserves the specified amount of memory so that subsequent LB_ADDSTRING messages take the shortest possible time. You can use estimates for the wParam and lParam parameters. If you overestimate, the extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the requested amount.

If the list box has the WS_HSCROLL style and you add a string wider than the list box, send an LB_SETHORIZONTALEXTENT message to ensure the horizontal scroll bar appears.

Usage example

CListBox.AddString(hListBox, "New string")

CalcHorizontalExtent

Calculates the size, in logical units, of the widest string item.

FUNCTION CListBox.CalcHorizontalExtent(BYVAL hListBox AS HWND) AS LONG

Return value

Returns the size, in logical units, of the widest string item in the ListBox.

Usage example

DIM cx AS LONG = CListBox.CalcHorizontalExtent(hListBox)

DeleteString

Deletes a string in a list box.

FUNCTION CListBox.DeleteString (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS LONG

Return value

The return value is a count of the strings remaining in the list. The return value is LB_ERR if the index parameter specifies an index greater than the number of items in the list.

Remarks

If an application creates the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the system sends a WM_DELETEITEM message to the owner of the list box so the application can free any additional data associated with the item.

Usage example

CListBox.DeleteString(hListBox, 5)

AddDir

Adds names to the list displayed by a list box. The message adds the names of directories and files that match a specified string and set of file attributes. It can also add mapped drive letters to the list box.

FUNCTION Dir (BYVAL hListBox AS HWND, BYVAL Attr AS DWORD, BYVAL pwszFileSpec AS WSTRING PTR) AS LONG

Return value

If the message succeeds, the return value is the zero-based index of the last name added to the list.

If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new strings, the return value is LB_ERRSPACE.

Remarks

The LB_INITSTORAGE message helps speed up the initialization of list boxes that have a large number of items (more than 100). It reserves the specified amount of memory so that subsequent LB_DIR messages take the shortest possible time. You can use estimates for the wParam and lParam parameters. If you overestimate, the extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the requested amount.

If Attr includes the DDL_DIRECTORY flag and pwszFileSpec specifies all the subdirectories of a first-level directory, such as C:\TEMP\*, the list box will always include a “..” entry for the root directory. This is true even if the root directory has hidden or system attributes and the DDL_HIDDEN and DDL_SYSTEM flags are not specified. The root directory of an NTFS volume has hidden and system attributes.

The list displays long filenames, if any.

Usage example

CListBox.Adddir(hListBox, DDL_DIRECTORY, filepath)

Disable

Disables the control

FUNCTION Disable (BYVAL hListBox AS HWND) AS BOOLEAN

Return value

False if the control was previous disabled; otherwise TRUE.

Usage example

CListBox.Disable(hListBox)

Enable

Enables the control

FUNCTION Enable (BYVAL hListBox AS HWND) AS BOOLEAN

Return value

Return value: False if the control was previous enabled; otherwise TRUE

Usage example

CListBox.Enable(hListBox)

FindItemData

Finds the first item in a list box that has the specified item data.

FUNCTION FindItemData (BYVAL hListBox AS HWND, BYVAL indexStart AS LONG, BYVAL pData AS ANY PTR) AS LONG

Return value

The return value is the index of the matching item, or LB_ERR if the search was unsuccessful.

Usage example

CListBox.FindItemData(hListBox, 4, pdata)

FindString

Finds the first string in a list box that begins with the specified string.

FUNCTION FindString (BYVAL hListBox AS HWND, BYVAL indexStart AS LONG, BYVAL pwszString AS WSTRING PTR) AS LONG

Return value

The return value is the index of the matching item, or LB_ERR if the search was unsuccessful.

Remarks

If the list box has the owner-drawn style but not the LBS_HASSTRINGS style, the action taken by LB_FINDSTRING depends on whether the LBS_SORT style is used. If LBS_SORT is used, the system sends WM_COMPAREITEM messages to the list box owner to determine which item matches the specified string.

Usage example

CListBox.FindString(hListBox, 4, "strig to find")

FindStringExact

Finds the first list box string that exactly matches the specified string, except that the search is not case sensitive.

FUNCTION FindStringExact (BYVAL hListBox AS HWND, BYVAL indexStart AS LONG, BYVAL pwszSearchString AS WSTRING PTR) AS LONG

Return value

The return value is the index of the matching item, or LB_ERR if the search was unsuccessful.

Remarks

This function is only successful if the specified string and a list box item have the same length (except for the null at the end of the specified string) and have exactly the same characters.

If the list box has the owner-drawn style but not the LBS_HASSTRINGS style, the action taken by LB_FINDSTRING depends on whether the LBS_SORT style is used. If LBS_SORT is used, the system sends WM_COMPAREITEM messages to the list box owner to determine which item matches the specified string.

Usage example

CListBox.FindStringExact(hListBox, 4, "strig to find")

GetAnchorIndex

Gets the index of the anchor item that is, the item from which a multiple selection starts. A multiple selection spans all items from the anchor item to the caret item.

FUNCTION GetAnchorIndex (BYVAL hListBox AS HWND) AS LONG

Return value

The return value is the zero-based index of the anchor item, or LB_ERR if an error occurs.

Usage example

DIM index AS LONG = CListBox.GetAnchorIndex(hListBox)

GetCaretIndex

Retrieves the index of the item that has the focus in a multiple-selection list box. The item may or may not be selected.

FUNCTION GetCaretIndex (BYVAL hListBox AS HWND) AS LONG

Return value

The return value is the zero-based index of the focused list box item, or 0 if no item has the focus.

Remarks

This message can also be used to get the index of the item that is currently selected in a single-selection list box.

Usage example

DIM index AS LONG = CListBox.GetCaretIndex(hListBox)

GetCount

Gets the number of items in a list box.

FUNCTION GetCount (BYVAL hListBox AS HWND) AS LONG

Return value

The return value is the number of items in the list box, or LB_ERR if an error occurs.

Remarks

The returned count is one greater than the index value of the last item (the index is zero-based).

Usage example

DIM count AS LONG = CListBox.GetCount(hListBox)

GetCurSel

Gets the index of the currently selected item, if any, in a list box.

FUNCTION GetCurSel (BYVAL hListBox AS HWND) AS LONG

Return value

The return value is the zero-based index of the currently selected item. If there is no selection, the return value is LB_ERR.

Usage example

DIM sel AS LONG = CListBox.GetCurSel(hListBox)

GetHorizontalExtent

Gets the width, in pixels, that a list box can be scrolled horizontally (the scrollable width) if the list box has a horizontal scroll bar.

FUNCTION GetHorizontalExtent (BYVAL hListBox AS HWND) AS LONG

Return value

The return value is the scrollable width, in pixels, of the list box.

Remarks

To respond to the LB_GETHORIZONTALEXTENT message, the list box must have been defined with the WS_HSCROLL style.

If the application does not set the horizontal extent of the list box (using LB_SETHORIZONTALEXTENT), the default horizontal extent is zero. Note that the list box does not update its horizontal extent dynamically.

Usage example

DIM cx AS LONG = CListBox.GetHorizontalExtent(hListBox)

GetListBoxInfo

Gets the number of items per column in a specified list box.

FUNCTION GetListBoxInfo (BYVAL hListBox AS HWND) AS LONG

Return value

The return value is the number of items per column.

Remarks

This message is equivalent to GetListBoxInfo.

Usage example

DIM items AS LONG = CListBox.GetListBoxInfo(hListBox)

GetItemData

Gets the application-defined value associated with the specified list box item.

FUNCTION GetItemData (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS ANY PTR

Return value

The return value is the value associated with the item, or LB_ERR if an error occurs. If the item is in an owner-drawn list box and was created without the LBS_HASSTRINGS style, this value was in the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message that added the item to the list box. Otherwise, it is the value in the lParam of the LB_SETITEMDATA message.

Usage example

DIM pData AS ANY PTR = CListBox.GetItemData(hListBox)

GetItemHeight

Gets the height of items in a list box.

FUNCTION GetItemHeight (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS LONG

Return value

The return value is the height, in pixels, of each item in the list box. The return value is the height of the item specified by the wParam parameter if the list box has the LBS_OWNERDRAWVARIABLE style. The return value is LB_ERR if an error occurs.

Usage example

DIM height AS LONG = CListBox.GetItemHeight(hListBox)

GetItemRect

Gets the dimensions of the rectangle that bounds a list box item as it is currently displayed in the list box.

FUNCTION GetItemRect (BYVAL hListBox AS HWND, BYVAL index AS LONG, BYVAL prc AS RECT PTR) AS LONG
FUNCTION GetItemRect (BYVAL hListBox AS HWND, BYVAL index AS LONG, BYREF rc AS RECT) AS LONG
FUNCTON GetItemRect (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS RECT

Return value

If an error occurs, the return value is LB_ERR.

Usage example

DIM rc AS RECT
CListBox.GetItemRect(hListBox, 5, @rc)
CListBox.GetItemRect(hListBox, 5, rc)
rc = CListBox.GetItemRect(hListBox, 5)

GetLocale

Gets the current locale of the list box. You can use the locale to determine the correct sorting order of displayed text (for list boxes with the LBS_SORT style) and of text added by the LB_ADDSTRING message.

FUNCTION GetLocale (BYVAL hListBox AS HWND) AS LONG

Return value

The return value specifies the current locale of the list box. The HIWORD contains the country/region code and the LOWORD contains the language identifier.

Remarks

The language identifier consists of a sublanguage identifier and a primary language identifier. Use the PRIMARYLANGID macro to extract the primary language identifier from the LOWORD of the return value, and the SUBLANGID macro to extract the sublanguage identifier.

Usage example

DIM locale AS LONG = CListBox.GetLocale(hListBox)

GetSel

Gets the selection state of an item.

FUNCTION GetSel (BYVAL hListBox AS HWND, BYVAL Index AS LONG) AS BOOLEAN

Return value

If an item is selected, the return value is greater than zero; otherwise, it is zero. If an error occurs, the return value is LB_ERR.

Usage example

DIM bSel AS BOOLEAN = CListBox.GetSel(hListBox)

GetSelCount

Gets the total number of selected items in a multiple-selection list box.

FUNCTION GetSelCount (BYVAL hListBox AS HWND) AS LONG

Return value

The return value is the count of selected items in the list box. If the list box is a single-selection list box, the return value is LB_ERR.

Usage example

DIM count AS LONG = CListBox.GetSelCount(hListBox)

GetSelect

The listbox is searched to find the first selected item. If the item parameter is included, searching starts at that position to facilitate retrieving multiple selected items. If item is omitted, the search starts at the first data item. The index number of the selected item is returned as the result of the function. If no item is selected, the value -1 is returned

FUNCTION GetSelect (BYVAL hListBox AS HWND, BYVAL startIndex AS LONG = 0) AS LONG

Return value

The index of the first select index; if no item is selected, the value -1 is returned

Usage example

DIM index AS LONG = CListBox.GetSelect(hListBox, 4)

GetSelItems

Fills a buffer with an array of integers that specify the item numbers of selected items in a multiple-selection list box.

FUNCTION GetSelItems (BYVAL hListBox AS HWND, BYVAL items AS DWORD, BYVAL prgItems AS LONG PTR) AS LONG

Return value

The return value is the number of items placed in the buffer. If the list box is a single-selection list box, the return value is LB_ERR.

GetText

Gets a string from a list box.

FUNCTION GetText (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS DWSTRING

Return value

The text of the item.

Usage example

DIM dwsText AS DWSTRING = CListBox.GetText(hListBox, 4)

GetTextLen

Gets the length of a string in a list box.

FUNCTION GetTextLen (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS LONG

Usage example

DIM nLen AS LONG = CListBox.GetTextLen(hListBox, 4)

GetTopIndex

Gets the index of the first visible item in a list box. Initially the item with index 0 is at the top of the list box, but if the list box contents have been scrolled another item may be at the top. The first visible item in a multiple-column list box is the top-left item.

FUNCTION GetTopIndex (BYVAL hListBox AS HWND) AS LONG

Return value

The return value is the index of the first visible item in the list box.

Usage example

DIM index AS LONG = CListBox.GetTopIndex(hListBox)

InitStorage

Allocates memory for storing list box items. This message can be used before an application adds a large number of items to a list box.

FUNCTION InitStorage (BYVAL hListBox AS HWND, BYVAL nItems AS DWORD, BYVAL nBytes AS DWORD) AS LONG

Return value

If the message is successful, the return value is the total number of items that the list box can store before a memory reallocation is needed.

If the message fails, the return value is LB_ERRSPACE.

Remarks

The LB_INITSTORAGE message helps speed up the initialization of list boxes that have a large number of items (more than 100). It reserves the specified amount of memory so that subsequent LB_ADDSTRING, LB_INSERTSTRING, LB_DIR, and LB_ADDFILE messages are more efficient. You can use estimates for the nItems and nBytes parameters. If you overestimate, the extra memory remains allocated; if you underestimate, the list box will allocate additional memory as necessary.

The memory required to store a string includes the null terminator. Therefore, if you plan to add 100 strings, each with a length of 10 characters, you would pass a nItems of 100 and an nBytes of 100 × (10 + 1) × sizeof(TCHAR).

Usage example

DIM items AS LONG = CListBox.InitStorage(hListBox, nItems, nBytes)

InsertItemData

Inserts item data to a list box.

FUNCTION InsertItemData (BYVAL hListBox AS HWND, BYVAL index AS LONG, BYVAL pData AS ANY PTR) AS LONG

Return value

The return value is the index of the position at which the string was inserted. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE.

Usage example

DIM index AS LONG = CListBox.InsertItemData(hListBox, 3, pData)

InsertString

Inserts a string or item data into a list box. Unlike the LB_ADDSTRING message, the LB_INSERTSTRING message does not cause a list with the LBS_SORT style to be sorted.

FUNCTION InsertString (BYVAL hListBox AS HWND, BYVAL index AS LONG, BYVAL pwszText AS WSTRING PTR) AS LONG

Return value

The return value is the index of the position at which the string was inserted. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE.

Remarks

The LB_INITSTORAGE message helps speed up the initialization of list boxes that have a large number of items (more than 100). It reserves the specified amount of memory so that subsequent LB_INSERTSTRING messages take the shortest possible time. You can use estimates for the wParam and lParam parameters. If you overestimate, the extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the requested amount.

If the list box has WS_HSCROLL style and you insert a string wider than the list box, send an LB_SETHORIZONTALEXTENT message to ensure the horizontal scroll bar appears.

Usage example

DIM index AS LONG = CListBox.InsertString(hListBox, 3, "Text string")

ItemFromPoint

Gets the zero-based index of the item nearest the specified point in a list box.

FUNCTION ItemFromPoint (BYVAL hListBox AS HWND, BYVAL x AS SHORT, BYVAL y AS SHORT) AS LONG

Usage example

DIM index AS LONG = CListBox.ItemFromPoint(hListBox, x, y)

RemoveDarkMode

Removes the control dark mode. Only affects the scroll bars.

FUNCTION RemoveDarkMode (BYVAL hListBox AS HWND) AS HRESULT

Usage example

CListBox.RemoveDarkMode(hListBox)

ReplaceString

Replaces a string, and his associated data, into a list box.

FUNCTION ReplaceString (BYVAL hListBox AS HWND, BYVAL index AS LONG, _
   BYVAL pwszNewText AS WSTRING PTR, BYVAL pNewData AS ANY PTR = NULL) AS LONG

Return value

The return value is the index of the position at which the string was inserted. As there is not a message to replace a string, the string is deleted and a new string is inserted.

Usage example

CListBox.ReplaceString(hListBox, 3, "New string")

ResetContent

Removes all items from a list box.

SUB ResetContent (BYVAL hListBox AS HWND)

Remarks

If the list box has an owner-drawn style but not the LBS_HASSTRINGS style, the owner of the list box receives a WM_DELETEITEM message for each item in the list box.

Usage example

CListBox.ResetContent(hListBox)

SelectItemData

Searches a list box for an item that has the specified item data. If a matching item is found, the item is selected.

SUB SelectItemData (BYVAL hListBox AS HWND, BYVAL indexStart AS LONG, BYVAL pData AS ANY PTR) AS LONG

Usage example

CListBox.SelectItemData(hListBox, 3, pData)

SelectString

Searches a list box for an item that begins with the characters in a specified string. If a matching item is found, the item is selected.

FUNCTION SelectString (BYVAL hListBox AS HWND, BYVAL start AS LONG, BYVAL pwszText AS WSTRING PTR) AS LONG
FUNCTION SelectString (BYVAL hListBox AS HWND, BYVAL index AS LONG =-1) AS LONG

Usage example

CListBox.SelectString(hListBox, 3, "Item 10")
CListBox.SelectString(hListBox, 5)

SelItemRange

Selects or deselects one or more consecutive items in a multiple-selection list box.

FUNCTION SelItemRange (BYVAL hListBox AS HWND, BYVAL fSel AS BOOLEAN, _
   BYVAL startIndex AS SHORT, BYVAL endIndex AS SHORT) AS LONG

Return value

If an error occurs, the return value is LB_ERR.

Remarks

Use this message only with multiple-selection list boxes.

This message can select a range only within the first 65,536 items.

Usage example

CListBox.SelItemRange(hListBox, TRUE, 3, 10)

SelItemRangeEx

Selects one or more consecutive items in a multiple-selection list box.

FUNCTION SelItemRangeEx (BYVAL hListBox AS HWND, BYVAL startIndex AS LONG, BYVAL endIndex AS LONG) AS LONG

Usage example

CListBox.SelItemRangeEx(hListBox, TRUE, 3, 10)

SetAnchorIndex

Sets the anchor item that is, the item from which a multiple selection starts. A multiple selection spans all items from the anchor item to the caret item.

FUNCTION SetAnchorIndex (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS LONG

Return value

If the message succeeds, the return value is zero.

If the message fails, the return value is LB_ERR.

Usage example

CListBox.SetAnchorIndex(hListBox, 4)

SetCaretIndex

Sets the focus rectangle to the item at the specified index in a multiple-selection list box. If the item is not visible, it is scrolled into view.

FUNCTION SetCaretIndex (BYVAL hListBox AS HWND, BYVAL index AS LONG, BYVAL fVisibility AS BOOLEAN = FALSE) AS LONG

Return value

If an error occurs, the return value is LB_ERR (-1). Otherwise, LB_OKAY (0) is returned.

Remarks

If this message is sent to a single-selection list box that does not contain a selected item, the caret index is set to the item specified by the fVisibility parameter. If the single-selection list box does contain a selected item, the list box returns LB_ERR.

SetColumnWidth

Sets the width, in pixels, of all columns in a multiple-column list box.

SUB SetColumnWidth (BYVAL hListBox AS HWND, BYVAL nWidth AS DWORD) AS LONG

Usage example

CListBox.SetColumnWidth(hListBox, 100)

SetCount

Sets the count of items in a list box created with the LBS_NODATA style and not created with the LBS_HASSTRINGS style.

SUB SetCount (BYVAL hListBox AS HWND, BYVAL nCount AS DWORD) AS LONG

Return value

If an error occurs, the return value is LB_ERR. If there is insufficient memory to store the items, the return value is LB_ERRSPACE.

Remarks

The LB_SETCOUNT message is supported only by list boxes created with the LBS_NODATA style and not created with the LBS_HASSTRINGS style. All other list boxes return LB_ERR.

Usage example

CListBox.SetCount(hListBox, 200)

SetCurSel

Selects a string and scrolls it into view, if necessary. When the new string is selected, the list box removes the highlight from the previously selected string.

SUB SetCurSel (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS LONG

Return value

If an error occurs, the return value is LB_ERR. If the wParam parameter is -1, the return value is LB_ERR even though no error occurred.

Remarks

Use this message only with single-selection list boxes. You cannot use it to set or remove a selection in a multiple-selection list box.

Usage example

CListBox.SetCurSel(hListBox, 200)

SetDarkMode

Set the control dark mode. Only affects the scroll bars.

FUNCTION CListBox.SetDarkMode (BYVAL hListBox AS HWND) AS HRESULT

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Usage example

CListBox.SetDarkMode(hListBox)

SetHorizontalExtent

Sets the width, in pixels, by which a list box can be scrolled horizontally (the scrollable width). If the width of the list box is smaller than this value, the horizontal scroll bar horizontally scrolls items in the list box. If the width of the list box is equal to or greater than this value, the horizontal scroll bar is hidden.

SUB SetHorizontalExtent (BYVAL hListBox AS HWND, BYVAL cxExtent AS LONG)

Remarks

To respond to the LB_SETHORIZONTALEXTENT message, the list box must have been defined with the WS_HSCROLL style.

Note that a list box does not update its horizontal extent dynamically.

This message has no effect on a multiple-column list box.

Usage example

CListBox.SetHorizontalExtent(hListBox, 300)

SetItemData

Sets a value associated with the specified item in a list box.

FUNCTION SetItemData (BYVAL hListBox AS HWND, BYVAL index AS LONG, BYVAL pData AS ANY PTR) AS LONG

Return value

If an error occurs, the return value is LB_ERR.

Remarks

If the item is in an owner-drawn list box created without the LBS_HASSTRINGS style, this message replaces the value contained in the pData parameter of the LB_ADDSTRING or LB_INSERTSTRING message that added the item to the list box.

Usage example

CListBox.SetItemData(hListBox, 10, pData)

SetItemHeight

Sets the height, in pixels, of items in a list box. If the list box has the LBS_OWNERDRAWVARIABLE style, this message sets the height of the item specified by the wParam parameter. Otherwise, this message sets the height of all items in the list box.

FUNCTION SetItemHeight (BYVAL hListBox AS HWND, BYVAL nHeight AS DWORD) AS LONG

Return value

If the index or height is invalid, the return value is LB_ERR.

Usage example

CListBox.SetItemHeight(hListBox, 30)

SetLocale

Sets the current locale of the list box. You can use the locale to determine the correct sorting order of displayed text (for list boxes with the LBS_SORT style) and of text added by the LB_ADDSTRING message.

FUNCTION SetLocale (BYVAL hListBox AS HWND, BYVAL wLocaleID AS DWORD) AS LONG

Return value

The return value is the previous locale identifier. If the wParam parameter specifies a locale that is not installed on the system, the return value is LB_ERR and the current list box locale is not changed.

Remarks

Use the MAKELCID macro to construct a locale identifier.

SetSel

Selects an item in a multiple-selection list box and, if necessary, scrolls the item into view.

FUNCTION SetSel (BYVAL hListBox AS HWND, BYVAL fSelect AS BOOLEAN, BYVAL index AS LONG = -1) AS LONG

Usage example

CListBox.SetSel(hListBox, TRUE, 10)

SetTabStops

Sets the tab-stop positions in a list box.

FUNCTION SetTabStops (BYVAL hListBox AS HWND, BYVAL cTabs AS LONG, BYVAL prgTabs AS LONG PTR)

Return value

If all the specified tabs are set, the return value is TRUE; otherwise, it is FALSE.

Remarks

To respond to the LB_SETTABSTOPS message, the list box must have been created with the LBS_USETABSTOPS style.

If cTabs is 0 and prgTabs is NULL, the default tab stop is two dialog template units. If cTabs is 1, the list box will have tab stops separated by the distance specified by prgTabs.

If prgTabs points to more than a single value, a tab stop will be set for each value in prgTabs, up to the number specified by cTabs.

The values specified by prgTabs are in dialog template units, which are the device-independent units used in dialog box templates. To convert measurements from dialog template units to screen units (pixels), use the MapDialogRect function.

SetText

Sets the tab-stop positions in a list box.

FUNCTION SetText (BYVAL hListBox AS HWND, BYVAL index AS LONG, BYVAL pwszNewText AS WSTRING PTR) AS LONG

Return value

The return value is the index of the position at which the string was inserted. As there is not a message to replace a string, the string is deleted and a new string is inserted.

Usage example

CListBox.SetText(hListBox, 3, "New string")

SetTopIndex

Ensures that a particular item in a list box is visible.

FUNCTION SetTopIndex (BYVAL hListBox AS HWND, BYVAL index AS LONG) AS LONG

Return value

If an error occurs, the return value is LB_ERR.

Remarks

The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

Usage example

CListBox.SetTopIndex(hListBox, 15)

UnselectString

Unselects the specified string in a multiple-selection list box.

FUNCTION UnselectString (BYVAL hListBox AS HWND, BYVAL index AS LONG = -1) AS LONG

Usage example

CListBox.UnselectString(hListBox, 5)